Что за Quarto?

Что за Quarto?

Quarto – не библиотека R, а автономное приложение с интерфейсом командной строки. Например, даже без установленных R или Python вы можете:

1. Создать документ document.md в своем любимом редакторе.
2. Добавить YAML-метаданные (как Rmarkdown, но см. ниже).
3. Сверстать документ в нужном вам формате.

quarto render document.md

Что за Quarto?

RStudio IDE новых версий включает Quarto, а также предоставляет для него редактор кода с автозаполнением и удобный визуальный редактор.

Quarto имеет более широкие по сравнению с Rmarkdown возможности. Можно воспринимать его как:

• Rmarkdown++;
• MS Word с гибридным интерфейсом;
• Dreamweaver для аналитиков и ученых.

Что нового: многоформатность

Что нового: модульный дизайн

Quarto позволяет разбивать анализ на маленькие, повторно используемые компоненты, которые можно собирать в сложные документы. Это делает повторное использование и комбинирование частей вашего анализа легким.

Сложный проект на R может состоять из нескольких скриптов, содержащих загрузку и предобработку данных, специальные функции, моделирование и визуализацию. Quarto позволяет точно так же использовать файлы .qmd: собирать их в большие проекты, использовать вывод одной ячейки кода много раз.

Пример: включить все объекты из файла _data.qmd

{{< include _data.qmd >}}

Что нового: модульный дизайн

Quarto позволяет использовать параметры, c которыми можно готовить разные отчеты из одного и того же документа, например:

• отчеты для разных регионов;
• отчеты для разных периодов;
• моделирование с разными допущениями или алгоритмами.

---
title : "Market Report"
…
params:
  job : "Бухгалтер"
  area: "Москва"
---

Что нового: модульный дизайн

Значения параметров используются в качестве шаблона в коде документа, например:

df_meta <- open_dataset('data/db/meta', partitioning = 'job_id') |>
  filter(
    job == params$job,
    area = params$area
  )

Затем документ можно сверстать с разными параметрами из R или командной строки:

quarto render doc.qmd -P job:"Бухгалтер" -P area:"Москва" --output doc.pdf

Что нового: модульный дизайн

Некоторые преимущества модульных документов включают:

1. Повторное использование: можно повторно использовать те же ячейки в нескольких документах.
2. Гибкость: можно повторно комбинировать ячейки разными способами для разных выводов или целей.
3. Абстракция: скрывать детали реализации от читателей документа.
4. Удобство поддержки: нужно вносить изменения только в одном месте.

Что нового: расширенное форматирование

Quarto изначально включает все необходимое для научных публикаций и воспроизводимого анализа:

• обширную поддержку перекрестных ссылок и цитат;
• расширенное аннотирование рисунков, таблиц и кода;
• нативную поддержку графов и блок-схем (mermaid и Graphviz);
• расширенные возможности написания формул \(\LaTeX\).

$$A = \begin{pmatrix}
    4&-3&-3\\
    1&2&1  \\
    1&1&2
  \end{pmatrix}$$

Что со всем этим делать?

Quarto «из коробки» позволяет создавать более 40 форматов документов (format: ваш-формат).

Для каждого формата доступны по нескольку десятков опций.

Знание CSS/SASS, \(\LaTeX\) или Pandoc дает почти безграничные возможности настройки внешнего вида отчетов.

Quarto динамично развивается, появляются новые возможности.

Общий алгоритм проектов Quarto

Кстати, код диаграммы:

```{mermaid}
%%| eval: false
flowchart LR
  A{Выбираем тип проекта} --> B(Редактируем YAML)
  B --> C(Пишем текст и код)
  B --> D(Добавляем изображения)
  C --> E(Настраиваем отображение)
  D --> E
  E <--> B
  E --> F[Публикация]
  
  classDef optional stroke-dasharray:10;
  class D optional
  class E optional
```

Как работает Quarto

При работе с R система Quarto сначала создает markdown-документ, который затем конвертируется в нужный формат программой pandoc.

Источник: Tom Mock на GitHub

Типы проекта

Проекты других доступных типов можно создать вручную, прописав format: [наш-формат]

Типы проекта

Из одного документа можно сверстать несколько документов в разных форматах. При этом отображение можно настроить отдельно для каждого формата.

format:
  html:
    theme: pulse
  pdf:
    fig-format: png

Типы проекта

Terminal

quarto install tinytex --update-path

format:
  html:
    theme: united
  pdf:
    papersize: A5
    fig-format: png
    include-in-header: 
      - file: packages.tex

Пример настройки: HTML

Опции HTML позволяют настраивать макет страницы, базовые элементы стиля и многое другое.

---
format:
  html:
    theme:
      light: pulse
      dark: cyborg
    css: styles.css
    mainfont: corbel
    fontsize: 1.1rem
    fontcolor: "#090103"
    linkcolor: "#E81444"
    monofont: consolas
    title-block-style: plain
    title-block-banner: "#DDBEED"
    title-block-banner-color: "#AA26EE"
    margin-top: 40px
---

Готовые темы Quarto представлены на сайте Bootswatch.

Пример настройки: PDF

В PDF тоже можно настраивать макет (и размер) страницы, базовые элементы стиля, а также добавлять файлы \(\TeX\) для более тонкой настройки.

---
format:
  pdf:
    mainfont: Georgia
    monofont: Consolas
    linkcolor: Bittersweet
    citecolor: Mahogany
    urlcolor: MediumOrchid
    papersize: A5
    fig-format: png
    include-in-header:
      - text: |
          \usepackage[english,russian]{babel}
          \usepackage{fontspec}
          \setsansfont{Courier New}
          \usepackage{amsmath,amsfonts,amssymb,amsthm,mathtools}
          \usepackage{icomma}
---

YAML-заголовки

YAML («YAML Ain’t Markup Language») – язык сериализации данных, как JSON и XML. Используется Quarto для записи конфигурации проекта. Формат записи – опция: значение.

Код конфигурации YAML отделяется тремя дефисами сверху и снизу:

---
title : "Hello, Quarto"
author: "otus.ru"
format:
  pptx:
    reference-doc: ../templates/template.pptx
    mermaid-format: png
---

YAML-заголовки

опция:
  - элемент1
    опция-элемента1: значение
  - элемент2

---
format:
  html:
    html-math-method: mathjax
    include-in-header:
     - text: |
          <script>
          window.MathJax = {
            loader: {
              load: ['[tex]/upgreek', '[tex]/boldsymbol', '[tex]/physics']
            },
            tex: {
              packages: {
                '[+]': ['upgreek', 'boldsymbol', 'physics']
              }
            }
          };
          </script>
---

YAML-заголовки

К метаданным можно обращаться через синтаксис Quarto {{<…>}}:

[{\{< meta author >}}]{style="font-family:Courier;font-size:3em;float:right;"}

![Otus: R для анализа данных]({\{< meta format.revealjs.logo >}}){#fig-otus-r-owl}

Фрагменты кода

Как и для Rmarkdown, возможность интерпретировать код и встраивать результаты его исполнения в документ является основной функциональной особенностью Quarto.

В Quarto опции для отдельного фрагмента кода, если они нужны, записываются внутри блока в формате YAML и начинаются с #|:

#| label: load-packages
#| include: false

library(tidymodels)

```{r}
#| label: ex-fold
#| code-fold: true
#| code-summary: 'Показать код'
x <- rchisq(1e3, 13)
```

Фрагменты кода

В Quarto очень легко подсвечивать строки кода:

```{r}
#| code-line-numbers: "2|3-4|6|7"
#| label: ex-highlight
#| eval: false

hist(x)
ggplot2::qplot(x, geom = 'histogram')
```

---
format:
  html: 
    code-block-bg:          "#fef"
    code-block-border-left: "#faf"
    highlight-style:        breeze
execute: 
  echo: fenced
---

Контейнеры pandoc

При работе в Quarto рекомендуется использовать универсальный формат контейнеров pandoc

1. Блочный контейнер – аналог <div> ограничивается двоеточиями (не менее 3) с опциональными атрибутами в фигурных скобках:

::: {style="border: 1px solid;font-size:0.2em;"}
Этот маленький текст будет окружен прямоугольной рамкой
:::

::: {.callout-note}
А это будет примечание
:::

Контейнеры pandoc

При работе в Quarto рекомендуется использовать универсальный формат контейнеров pandoc

2. Строчный контейнер – аналог <span> записывается в квадартных скобках, за которыми следуют атрибуты в фигурных скобках:

[Сначала id, потом класс, потом все остальное]{#id .class key1="val1" key2="val2"}

[Красный текст]{style="color:#d00;"}

Форматирование изображений

Синтаксис изображений похож на гиперссылки, но с восклицательным знаком в начале:

![Собачка](doge.png "Изображение собаки"){height=2cm}

Надпись в квадратных скобках считается подписью к изображению. Ее можно оставить пустой.

Текст в кавычках после url изображения – его всплывающее название (<img … title=…>)

Форматирование изображений

Можно добавлять атрибуты, например, выравнивание:

![Собачка](doge.png "Изображение собаки побольше"){fig-align="left" fig-alt="Изображение собаки"}

Собачка

Форматирование изображений

Можно сгруппировать несколько изображений и расположить их определенным образом:

::: {#fig-two-triangles layout-ncol=2}

![Первая картинка](tred.png){#fig-triangle-red width=20}

![Вторая картинка](tblue.png){#fig-triangle-blue width=20}

Две картинки
:::

Форматирование изображений

Если назвать контейнер с изображениями #fig-…, Quarto представит его как одно изображение из нескольких частей (как на предыдущем слайде) и пронумерует соответсвенно.

На изображения можно ссылаться: Рис. 2

Кстати, по умолчанию названия сопровождаются префиксом «Figure». Это можно изменить в настройках проекта:

crossref:
  fig-title: Рис.         # Подпись к изображению (по умолчанию "Figure")
  tbl-title: Таблица      # Подпись к таблице (по умолчанию "Table")
  subref-labels: arabic   # (по умолчанию "a, b, …, z")
  fig-prefix: Рис.        # Префикс ссылки на изображение
  tbl-prefix: Таблице     # Префикс ссылки на таблицу

Форматирование изображений

Для изображений, генерируемых кодом, параметры задают внутри блока:

```{r}
#| fig-cap: "Две диаграммы"
#| fig-subcap:
#|   - "Первая диаграмма"
#|   - "Вторая диаграмма"
#| layout: "[20, 10]"
#| fig-width: 30

hist(mtcars$mpg)
hist(mtcars$disp)
```

Форматирование изображений

Блок кода, чье название начинается с fig-, генерирует пронумерованные изображения, на которые можно ссылаться:

```{r}
#| label: fig-two-plots
#| fig-cap: "Две диаграммы"
#| fig-subcap:
#|   - "Первая диаграмма"
#|   - "Вторая диаграмма"
#| fig-width: 50
#| layout: "[10, 10]"
hist(mtcars$mpg)
hist(mtcars$disp)
```

Сайты, блоги, книги

Quarto содержит нативную поддержку создания комплексных публикаций:

• сайты;
• блоги;
• книги.

Создание сайта в Quarto – Заготовка

Проще всего создать сайт, блог или книгу как проект RStudio:

Создание сайта в Quarto – Метаданные

Информация о проекте, в том числе ссылки на контент,  описание структуры и общий стиль, содержится в файле _quarto.yml:

---
project:
  type: website

website:
  title: "quartosite"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme:
      light: united
      dark: vapor
    css: styles.css
    toc: true
---

Создание сайта в Quarto – Навигация

В Quarto можно легко создать следующие элементы навигации:

• navbar (навигационная панель сверху);
• sidebar (боковая навигационная панель);
• page-footer (подвал сайта);
• search (поисковый виджет).

Создание сайта в Quarto – Навигация

Пример задания верхней навигационной панели:

website:
  <…>
  # Верхняя панель («шапка»)
  navbar:
    title: "QuartoWebsite" # Переписывает website: title
    logo: www/owls_R.png
    logo-alt: "Otus: R for Data Analysis"
    # Элементы слева
    left:
      - href: index.qmd
        text: Home
      - about.qmd
    # Элементы справа
    right: 
      - href: https://otus.ru
        icon: mortarboard
        target: _blank

Создание сайта в Quarto – Навигация

Пример задания боковой панели:

website:
  <…>
  # Боковая панель (боковое меню):
  sidebar:
    background: dark  # Один из стандартных цветов текущей темы оформления
    foreground: light # Еще один цвет темы. Они изменятся, если изменить тему
    style: docked     # Прикреплена к своему краю
    contents:
      - section: "Первый раздел"
        contents:
          - entry-01.qmd
          - entry-02.qmd
      - section: "Второй раздел"
        contents:
          - entry-03.qmd
          - entry-04.qmd

Создание сайта в Quarto – Навигация

Пример задания нижней панели (подвала):

website:
  <…>
  # Подвал
  page-footer:
    background: primary  # «Ведущий» цвет выбранной темы оформления
    foreground: "#eee"
    # Элементы посередине (также можно указать right и left):
    center: 
      - about.qmd

Создание сайта в Quarto – Навигация

Пример задания поискового виджета:

website:
  <…>
  # Поиск
  search:
    location: navbar # К чему прикрепляется виджет
    type: overlay    # Тип: overlay – иконка со всплывающим виджетом, textbox – стандартный text input
    limit: 5         # Максимальное количество результатов для показа

Создание сайта в Quarto – Рендеринг

Для предпросмотра нашего сайта находим:

1. Меню проекта
2. Вкладку Build
3. Кнопку Render Website

Создание сайта в Quarto – Публикация

Помимо собственного сервера, опубликовать сайт можно на Quarto Pub, Posit Connect, GitHub Pages, Netlify и некоторых других платформах.

Создание сайта в Quarto – Публикация

Рассмотрим публикацию на GitHub Pages:

1. Прописываем, что папка с сайтом должна называться “docs” (по умолчанию “_site”)

project:
  type: website
  output-dir: docs

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/username/name.git
git push -u origin main

Создание сайта в Quarto – Публикация

4. В настройках репозитория в меню Pages разрешаем развертывание на Pages: выбираем ветку и папку (Рис. 5)

Рефлексия

Спросите себя. Расскажите в чате или голосом: